Notes on EPANET binary results (flow) file
EPANE 2.0 stock
Binary file structure
Static data section contains data about simulation run which is time independent
Dynamic results sections contain calculated results for a given time step
All data is binary output from internal EPANET internal data structures no textual data.
In EPANET 2.0 both single species quality simulation and MSX quality simulation required a binary flow results file as input. Their design was required a binary flow file as input, which contain the results for the full duration of the simulation interval, thereby precluding any incremental time step simulations
EPANET 2.0 with GQC Extensions
In order to support incremental time steps quality simulations the flowing extensions were added
The file open routine in EPANET and MSX were modified to open the binary flow results file in shared mode instead of exclusive mode
EPANET opened it in Write only mode when doing flow simulation
EPANET when doing single species quality simulation and MSX opened it in Read only mode
Additional methods were added to allow reposition the access pointer in the file and used to manipulate access to the file so it always had the show below
One additional piece of trickery was required. The EPANET 2.0 code reused some data structure when doing flow and single species quality analysis therefore doing simulations flow and quality simulations using a EPANET dll would result on the execution of a quality time step simulation stepping on some data needed for the next flow time step simulation. The workaround was to make a coy of the EPANET dll and rename it. The Windows Loader would then think there were two separate dlls and load one for the flow simulation and the other for the single quality simulation. This issue did not occur with MSX quality simulations since the MSX dll is a totally different animal.
The change to the structure of the binary results file when doing incremental quality simulations broke other EPANET application which depended on the binary result file
EPANET 2.1 Quality
In EPANET 2.1 the sharing of data structure between flow and single species quality simulation was eliminated and method were added to allow increment time step single species quality simulation using flow simulation results access from the common dll memory data structures. These changes eliminated the need to pass flow results via an external file when doing single species quality simulations. Since MSX uses a separate dll flow data still needed to be passed via an external file
EPANET 2.2 MSX quality
I have recently been giving some though to how to implement incremental time step MSX quality simulations with breaking other EPANET utilities which depend on the EPANET results fille.
I believe the flowing extensions would do the job
Modify the EPANET and MSX code file open routine to open the binary results file in shared rather than exclusive mode. EPANET opens Write Only and MSX opens Red Only
Add to file location variables current position and end file position to the MSX code base
Add a method to the MSX code base that can becalled with the name of the binary results file once EPANET has complete it initialization routines but before executing any time steps
One this method is called MSX would set its current position location to the end of the binary file which would be the end of the static data section in the file
When the MSX quality step method is called it would set the end of file position to the current file end, then repositio9n the file access pointer to the value of its current position variable and read flow data for one time step from the file and execute a single timestep simulation. Then reposition the file access pointer to the value saved in its end of file position variable and copy the value of the end of file variable to the current file position variable
Binary file structure
Note Re Multiple Simultaneous and Single Species Quality Simulation in EPANET 2.2
EPANET 2.2 Added the ability to do multiple simultaneous simulation by run several simulations a the same time with each simulation running on its own thread of execution.
In order to implement this feature the EPANET data structure where bundled in to a super data structure and each simulation run instantiates a instance of one of the structures when it is opened New version of all the EPANET method with names of the form EN_XXXX where ENXXXX was a pre EPANET 2.2 name. Each of these methods take an additional parameter which is a pointer to one of the supper data structures. Since the ability to do incremental flow and single species quality simulation depends on the ability to share flow data via memory, I believe running a flow and its associated single species quality simulation on separate threads is not possible.
To provide backward compatibility the pre 2.2 ENXXXX methods were retained but rewritten to be wrapper stubs which call the associated EN_XXXX method using a default super data structure which is implemented as a C static data structure.
Email Notes
Calling MSX an extension to EPANET is a misnomer. MSX is a separate executable or dll the only connection between it and EPANET is that MX required flow information generated by EPANET as input. MSX obtains that information by reading a BINARRY results file written by EPANET.
If the structure of that file is unchanged from the one generated by EPANET 2.0 MSX should continue to work as before if not the file input reading section of MSX will need to be modified to match the new EPANET file format.
The quickest way I can think for testing MSX compatibility with EPANET 2.2 Is to:: generate and save binary output files for flow only runs from the same data set using EPANET 2.0 and EPANET 2.2 Write a simple program using a language of choice, which opens two files, reads a block of data of data from each, does a byte by byte compare of the two blocks and repeats until reaching the end of file If the two fi8les match we home free if not we will need to determine the differences and make the required changes to the MSX file reading code Two additional steps are required in order to ensure complete compatibility EPANET 2,1 Added the ability to does incremental flow and single species quality simulations in the in the same run. One therefore needs to generated a binary output file from such a run a verify it matches a EPANET 2.0 flow only simulation. If not changes to the MSX file reader for flow data will be required. EPANET 2.2 added two additional features, Additional flow information results and the ability to perform multiple simulation in the same simulation run. For complete compatibility we need to generate binary output file using these new features and verify they match a 2.0 binary output file and if not make modification to the MSX binary file reader to allow usage of the new file formats.
There were additional issues in past if one wanted to do incremental time step quality simulation either single or multi step which required GQC specific extensions to both EPANET 2.0 and MSX code Please see the attached WORD document on the EPANET binary file structure for more details